home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 726-750 / 733 / termcap / info.lha / termcap.info-2 (.txt) < prev    next >
GNU Info File  |  1992-09-27  |  44KB  |  715 lines

  1. This is Info file termcap.info, produced by Makeinfo-1.44 from the
  2. input file termcap.texinfo.
  3.    This file documents the termcap library of the GNU system.
  4.    Copyright (C) 1988 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of
  6. this manual provided the copyright notice and this permission notice
  7. are preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided that
  10. the entire resulting derived work is distributed under the terms of a
  11. permission notice identical to this one.
  12.    Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions, except that this permission notice may be stated in a
  15. translation approved by the Foundation.
  16. File: termcap.info,  Node: Naming,  Next: Inheriting,  Prev: Capability Format,  Up: Data Base
  17. Terminal Type Name Conventions
  18. ==============================
  19.    There are conventions for choosing names of terminal types.  For
  20. one thing, all letters should be in lower case.  The terminal type for
  21. a terminal in its most usual or most fundamental mode of operation
  22. should not have a hyphen in it.
  23.    If the same terminal has other modes of operation which require
  24. different terminal descriptions, these variant descriptions are given
  25. names made by adding suffixes with hyphens.  Such alternate
  26. descriptions are used for two reasons:
  27.    * When the terminal has a switch that changes its behavior.  Since
  28.      the computer cannot tell how the switch is set, the user must
  29.      tell the computer by choosing the appropriate terminal type name.
  30.      For example, the VT-100 has a setup flag that controls whether the
  31.      cursor wraps at the right margin.  If this flag is set to "wrap",
  32.      you must use the terminal type `vt100-am'.  Otherwise you must
  33.      use `vt100-nam'.  Plain `vt100' is defined as a synonym for
  34.      either `vt100-am' or `vt100-nam' depending on the preferences of
  35.      the local site.
  36.      The standard suffix `-am' stands for "automatic margins".
  37.    * To give the user a choice in how to use the terminal.  This is
  38.      done when the terminal has a switch that the computer normally
  39.      controls.
  40.      For example, the Ann Arbor Ambassador can be configured with many
  41.      screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
  42.      characters but more lines let you see more of what you are
  43.      editing.  As a result, users have different preferences. 
  44.      Therefore, termcap provides terminal types for many screen sizes.
  45.       If you choose type `aaa-30', the terminal will be configured to
  46.      use 30 lines; if you choose `aaa-48', 48 lines will be used, and
  47.      so on.
  48.    Here is a list of standard suffixes and their conventional meanings:
  49.      Short for "wide".  This is a mode that gives the terminal more
  50.      columns than usual.  This is normally a user option.
  51. `-am'
  52.      "Automatic margins".  This is an alternate description for use
  53.      when the terminal's margin-wrap switch is on; it contains the `am'
  54.      flag.  The implication is that normally the switch is off and the
  55.      usual description for the terminal says that the switch is off.
  56. `-nam'
  57.      "No automatic margins".  The opposite of `-am', this names an
  58.      alternative description which lacks the `am' flag.  This implies
  59.      that the terminal is normally operated with the margin-wrap switch
  60.      turned on, and the normal description of the terminal says so.
  61. `-na'
  62.      "No arrows".  This terminal description initializes the terminal
  63.      to keep its arrow keys in local mode.  This is a user option.
  64. `-rv'
  65.      "Reverse video".  This terminal description causes text output for
  66.      normal video to appear as reverse, and text output for reverse
  67.      video to come out as normal.  Often this description differs from
  68.      the usual one by interchanging the two strings which turn reverse
  69.      video on and off.
  70.      This is a user option; you can choose either the "reverse video"
  71.      variant terminal type or the normal terminal type, and termcap
  72.      will obey.
  73.      "Status".  Says to enable use of a status line which ordinary
  74.      output does not touch (*note Status Line::.).
  75.      Some terminals have a special line that is used only as a status
  76.      line.  For these terminals, there is no need for an `-s' variant;
  77.      the status line commands should be defined by default.  On other
  78.      terminals, enabling a status line means removing one screen line
  79.      from ordinary use and reducing the effective screen height.  For
  80.      these terminals, the user can choose the `-s' variant type to
  81.      request use of a status line.
  82. `-NLINES'
  83.      Says to operate with NLINES lines on the screen, for terminals
  84.      such as the Ambassador which provide this as an option.  Normally
  85.      this is a user option; by choosing the terminal type, you control
  86.      how many lines termcap will use.
  87. `-NPAGESp'
  88.      Says that the terminal has NPAGES pages worth of screen memory,
  89.      for terminals where this is a hardware option.
  90. `-unk'
  91.      Says that description is not for direct use, but only for
  92.      reference in `tc' capabilities.  Such a description is a kind of
  93.      subroutine, because it describes the common characteristics of
  94.      several variant descriptions that would use other suffixes in
  95.      place of `-unk'.
  96. File: termcap.info,  Node: Inheriting,  Next: Changing,  Prev: Naming,  Up: Data Base
  97. Inheriting from Related Descriptions
  98. ====================================
  99.    When two terminal descriptions are similar, their identical parts
  100. do not need to be given twice.  Instead, one of the two can be defined
  101. in terms of the other, using the `tc' capability.  We say that one
  102. description "refers to" the other, or "inherits from" the other.
  103.    The `tc' capability must be the last one in the terminal
  104. description, and its value is a string which is the name of another
  105. terminal type which is referred to.  For example,
  106.      N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
  107.              :ti=\E[2J\E[30;0;0;30p:\
  108.              :te=\E[60;0;0;30p\E[30;1H\E[J:\
  109.              :li#30:tc=aaa-unk:
  110. defines the terminal type `aaa-30' (also known as plain `aaa') in
  111. terms of `aaa-unk', which defines everything about the Ambassador that
  112. is independent of screen height.  The types `aaa-36', `aaa-48' and so
  113. on for other screen heights are likewise defined to inherit from
  114. `aaa-unk'.
  115.    The capabilities overridden by `aaa-30' include `li', which says
  116. how many lines there are, and `ti' and `te', which configure the
  117. terminal to use that many lines.
  118.    The effective terminal description for type `aaa' consists of the
  119. text shown above followed by the text of the description of `aaa-unk'.
  120.  The `tc' capability is handled automatically by `tgetent', which
  121. finds the description thus referenced and combines the two descriptions
  122. (*note Find::.).  Therefore, only the implementor of the terminal
  123. descriptions needs to think about using `tc'.  Users and application
  124. programmers do not need to be concerned with it.
  125.    Since the reference terminal description is used last, capabilities
  126. specified in the referring description override any specifications of
  127. the same capabilities in the reference description.
  128.    The referring description can cancel out a capability without
  129. specifying any new value for it by means of a special trick.  Write
  130. the capability in the referring description, with the character `@'
  131. after the capability name, as follows:
  132.      NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
  133.              :am@:tc=aaa-30:
  134. File: termcap.info,  Node: Changing,  Prev: Inheriting,  Up: Data Base
  135. When Changes in the Data Base Take Effect
  136. =========================================
  137.    Each application program must read the terminal description from the
  138. data base, so a change in the data base is effective for all jobs
  139. started after the change is made.
  140.    The change will usually have no effect on a job that have been in
  141. existence since before the change. The program probably read the
  142. terminal description once, when it was started, and is continuing to
  143. use what it read then.  If the program does not have a feature for
  144. reexamining the data base, then you will need to run it again
  145. (probably killing the old job).
  146.    If the description in use is coming from the `TERMCAP' environment
  147. variable, then the data base file is effectively overridden, and
  148. changes in it will have no effect until you change the `TERMCAP'
  149. variable as well.  For example, some users' `.login' files
  150. automatically copy the terminal description into `TERMCAP' to speed
  151. startup of applications.  If you have done this, you will need to
  152. change the `TERMCAP' variable to make the changed data base take
  153. effect.
  154. File: termcap.info,  Node: Capabilities,  Next: Summary,  Prev: Data Base,  Up: Top
  155. Definitions of the Terminal Capabilities
  156. ****************************************
  157.    This section is divided into many subsections, each for one aspect
  158. of use of display terminals.  For writing a display program, you
  159. usually need only check the subsections for the operations you want to
  160. use.  For writing a terminal description, you must read each
  161. subsection and fill in the capabilities described there.
  162.    String capabilities that are display commands may require numeric
  163. parameters (*note Parameters::.).  Most such capabilities do not use
  164. parameters.  When a capability requires parameters, this is explicitly
  165. stated at the beginning of its definition.  In simple cases, the first
  166. or second sentence of the definition mentions all the parameters, in
  167. the order they should be given, using a name in upper case for each
  168. one.  For example, the `rp' capability is a command that requires two
  169. parameters; its definition begins as follows:
  170.      String of commands to output a graphic character C, repeated N
  171.      times.
  172.    In complex cases or when there are many parameters, they are
  173. described explicitly.
  174.    When a capability is described as obsolete, this means that
  175. programs should not be written to look for it, but terminal
  176. descriptions should still be written to provide it.
  177.    When a capability is described as very obsolete, this means that it
  178. should be omitted from terminal descriptions as well.
  179. * Menu:
  180. * Basic::                       Basic characteristics.
  181. * Screen Size::                 Screen size, and what happens when it changes.
  182. * Cursor Motion::               Various ways to move the cursor.
  183. * Wrapping::                    What happens if you write a character in the last column.
  184. * Scrolling::                   Pushing text up and down on the screen.
  185. * Windows::                     Limiting the part of the window that output affects.
  186. * Clearing::                    Erasing one or many lines.
  187. * Insdel Line::                 Making new blank lines in mid-screen; deleting lines.
  188. * Insdel Char::                 Inserting and deleting characters within a line.
  189. * Standout::                    Highlighting some of the text.
  190. * Underlining::                 Underlining some of the text.
  191. * Cursor Visibility::           Making the cursor more or less easy to spot.
  192. * Bell::                        Attracts user's attention; not localized on the screen.
  193. * Keypad::                      Recognizing when function keys or arrows are typed.
  194. * Meta Key::                    META acts like an extra shift key.
  195. * Initialization::              Commands used to initialize or reset the terminal.
  196. * Pad Specs::                   Info for the kernel on how much padding is needed.
  197. * Status Line::                 A status line displays "background" information.
  198. * Half-Line::                   Moving by half-lines, for superscripts and subscripts.
  199. * Printer::                     Controlling auxiliary printers of display terminals.
  200. File: termcap.info,  Node: Basic,  Next: Screen Size,  Prev: Capabilities,  Up: Capabilities
  201. Basic Characteristics
  202. =====================
  203.    This section documents the capabilities that describe the basic and
  204. nature of the terminal, and also those that are relevant to the output
  205. of graphic characters.
  206.      Flag whose presence means that the terminal can overstrike.  This
  207.      means that outputting a graphic character does not erase whatever
  208.      was present in the same character position before.  The terminals
  209.      that can overstrike include printing terminals, storage tubes
  210.      (all obsolete nowadays), and many bit-map displays.
  211.      Flag whose presence means that outputting a space can erase an
  212.      overstrike.  If this is not present and overstriking is supported,
  213.      output of a space has no effect except to move the cursor.
  214.      Flag whose presence means that this terminal type is a generic
  215.      type which does not really describe any particular terminal. 
  216.      Generic types are intended for use as the default type assigned
  217.      when the user connects to the system, with the intention that the
  218.      user should specify what type he really has.  One example of a
  219.      generic type is the type `network'.
  220.      Since the generic type cannot say how to do anything interesting
  221.      with the terminal, termcap-using programs will always find that
  222.      the terminal is too weak to be supported if the user has failed
  223.      to specify a real terminal type in place of the generic one.  The
  224.      `gn' flag directs these programs to use a different error
  225.      message: "You have not specified your real terminal type", rather
  226.      than "Your terminal is not powerful enough to be used".
  227.      Flag whose presence means this is a hardcopy terminal.
  228.      String of commands to output a graphic character C, repeated N
  229.      times.  The first parameter value is the ASCII code for the
  230.      desired character, and the second parameter is the number of
  231.      times to repeat the character.  Often this command requires
  232.      padding proportional to the number of times the character is
  233.      repeated.  This effect can be had by using parameter arithmetic
  234.      with `%'-sequences to compute the amount of padding, then
  235.      generating the result as a number at the front of the string so
  236.      that `tputs' will treat it as padding.
  237.      Flag whose presence means that the ASCII character `~' cannot be
  238.      output on this terminal because it is used for display commands.
  239.      Programs handle this flag by checking all text to be output and
  240.      replacing each `~' with some other character(s).  If this is not
  241.      done, the screen will be thoroughly garbled.
  242.      The old Hazeltine terminals that required such treatment are
  243.      probably very rare today, so you might as well not bother to
  244.      support this flag.
  245.      String whose presence means the terminal has a settable command
  246.      character.  The value of the string is the default command
  247.      character (which is usually ESC).
  248.      All the strings of commands in the terminal description should be
  249.      written to use the default command character.  If you are writing
  250.      an application program that changes the command character, use the
  251.      `CC' capability to figure out how to translate all the display
  252.      commands to work with the new command character.
  253.      Most programs have no reason to look at the `CC' capability.
  254.      Flag whose presence identifies Superbee terminals which are
  255.      unable to transmit the characters ESC and `Control-C'.  Programs
  256.      which support this flag are supposed to check the input for the
  257.      code sequences sent by the F1 and F2 keys, and pretend that ESC
  258.      or `Control-C' (respectively) had been read.  But this flag is
  259.      obsolete, and not worth supporting.
  260. File: termcap.info,  Node: Screen Size,  Next: Cursor Motion,  Prev: Basic,  Up: Capabilities
  261. Screen Size
  262. ===========
  263.    A terminal description has two capabilities, `co' and `li', that
  264. describe the screen size in columns and lines.  But there is more to
  265. the question of screen size than this.
  266.    On some operating systems the "screen" is really a window and the
  267. effective width can vary.  On some of these systems, `tgetnum' uses
  268. the actual width of the window to decide what value to return for the
  269. `co' capability, overriding what is actually written in the terminal
  270. description.  On other systems, it is up to the application program to
  271. check the actual window width using a system call.  For example, on
  272. BSD 4.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will
  273. tell you the current screen size.
  274.    On all window systems, termcap is powerless to advise the
  275. application program if the user resizes the window.  Application
  276. programs must deal with this possibility in a system-dependent
  277. fashion.  On some systems the C shell handles part of the problem by
  278. detecting changes in window size and setting the `TERMCAP' environment
  279. variable appropriately.  This takes care of application programs that
  280. are started subsequently.  It does not help application programs
  281. already running.
  282.    On some systems, including BSD 4.3, all programs using a terminal
  283. get a signal named `SIGWINCH' whenever the screen size changes. 
  284. Programs that use termcap should handle this signal by using `ioctl
  285. TIOCGWINSZ' to learn the new screen size.
  286.      Numeric value, the width of the screen in character positions. 
  287.      Even hardcopy terminals normally have a `co' capability.
  288.      Numeric value, the height of the screen in lines.
  289. File: termcap.info,  Node: Cursor Motion,  Next: Wrapping,  Prev: Screen Size,  Up: Capabilities
  290. Cursor Motion
  291. =============
  292.    Termcap assumes that the terminal has a "cursor", a spot on the
  293. screen where a visible mark is displayed, and that most display
  294. commands take effect at the position of the cursor.  It follows that
  295. moving the cursor to a specified location is very important.
  296.    There are many terminal capabilities for different cursor motion
  297. operations.  A terminal description should define as many as possible,
  298. but most programs do not need to use most of them.  One capability,
  299. `cm', moves the cursor to an arbitrary place on the screen; this by
  300. itself is sufficient for any application as long as there is no need
  301. to support hardcopy terminals or certain old, weak displays that have
  302. only relative motion commands.  Use of other cursor motion
  303. capabilities is an optimization, enabling the program to output fewer
  304. characters in some common cases.
  305.    If you plan to use the relative cursor motion commands in an
  306. application program, you must know what the starting cursor position
  307. is.  To do this, you must keep track of the cursor position and update
  308. the records each time anything is output to the terminal, including
  309. graphic characters.  In addition, it is necessary to know whether the
  310. terminal wraps after writing in the rightmost column.  *Note
  311. Wrapping::.
  312.    One other motion capability needs special mention: `nw' moves the
  313. cursor to the beginning of the following line, perhaps clearing all the
  314. starting line after the cursor, or perhaps not clearing at all.  This
  315. capability is a least common denominator that is probably supported
  316. even by terminals that cannot do most other things such as `cm' or
  317. `do'.  Even hardcopy terminals can support `nw'.
  318.      String of commands to position the cursor at line L, column C. 
  319.      Both parameters are origin-zero, and are defined relative to the
  320.      screen, not relative to display memory.
  321.      All display terminals except a few very obsolete ones support
  322.      `cm', so it is acceptable for an application program to refuse to
  323.      operate on terminals lacking `cm'.
  324.      String of commands to move the cursor to the upper left corner of
  325.      the screen (this position is called the "home position").  In
  326.      terminals where the upper left corner of the screen is not the
  327.      same as the beginning of display memory, this command must go to
  328.      the upper left corner of the screen, not the beginning of display
  329.      memory.
  330.      Every display terminal supports this capability, and many
  331.      application programs refuse to operate if the `ho' capability is
  332.      missing.
  333.      String of commands to move the cursor to the lower left corner of
  334.      the screen.  On some terminals, moving up from home position does
  335.      this, but programs should never assume that will work.  Just
  336.      output the `ll' string (if it is provided); if moving to home
  337.      position and then moving up is the best way to get there, the
  338.      `ll' command will do that.
  339.      String of commands to move the cursor to the beginning of the
  340.      line it is on.  If this capability is not specified, many
  341.      programs assume they can use the ASCII carriage return character
  342.      for this.
  343.      String of commands to move the cursor left one column.  Unless the
  344.      `bw' flag capability is specified, the effect is undefined if the
  345.      cursor is at the left margin; do not use this command there.  If
  346.      `bw' is present, this command may be used at the left margin, and
  347.      it wraps the cursor to the last column of the preceding line.
  348.      String of commands to move the cursor right one column.  The
  349.      effect is undefined if the cursor is at the right margin; do not
  350.      use this command there, not even if `am' is present.
  351.      String of commands to move the cursor vertically up one line.  The
  352.      effect of sending this string when on the top line is undefined;
  353.      programs should never use it that way.
  354.      String of commands to move the cursor vertically down one line. 
  355.      The effect of sending this string when on the bottom line is
  356.      undefined; programs should not use it that way.
  357.      Some programs do use `do' to scroll up one line if used at the
  358.      bottom line, if `sf' is not defined but `sr' is.  This is only to
  359.      compensate for certain old, incorrect terminal descriptions.  (In
  360.      principle this might actually lead to incorrect behavior on other
  361.      terminals, but that seems to happen rarely if ever.)  But the
  362.      proper solution is that the terminal description should define
  363.      `sf' as well as `do' if the command is suitable for scrolling.
  364.      The original idea was that this string would not contain a newline
  365.      character and therefore could be used without disabling the
  366.      kernel's usual habit of converting of newline into a
  367.      carriage-return newline sequence.  But many terminal descriptions
  368.      do use newline in the `do' string, so this is not possible; a
  369.      program which sends the `do' string must disable output
  370.      conversion in the kernel (*note Initialize::.).
  371.      Flag whose presence says that `le' may be used in column zero to
  372.      move to the last column of the preceding line.  If this flag is
  373.      not present, `le' should not be used in column zero.
  374.      String of commands to move the cursor to start of next line,
  375.      possibly clearing rest of line (following the cursor) before
  376.      moving.
  377. `DO', `UP', `LE', `RI'
  378.      Strings of commands to move the cursor N lines down vertically,
  379.      up vertically, or N columns left or right.  Do not attempt to
  380.      move past any edge of the screen with these commands; the effect
  381.      of trying that is undefined.  Only a few terminal descriptions
  382.      provide these commands, and most programs do not use them.
  383.      String of commands to position the cursor at line L, column C,
  384.      relative to display memory.  Both parameters are origin-zero. 
  385.      This capability is present only in terminals where there is a
  386.      difference between screen-relative and memory-relative
  387.      addressing, and not even in all such terminals.
  388.      String of commands to position the cursor at column C in the same
  389.      line it is on.  This is a special case of `cm' in which the
  390.      vertical position is not changed.  The `ch' capability is
  391.      provided only when it is faster to output than `cm' would be in
  392.      this special case.  Programs should not assume most display
  393.      terminals have `ch'.
  394.      String of commands to position the cursor at line L in the same
  395.      column.  This is a special case of `cm' in which the horizontal
  396.      position is not changed.  The `cv' capability is provided only
  397.      when it is faster to output than `cm' would be in this special
  398.      case.  Programs should not assume most display terminals have
  399.      `cv'.
  400.      String of commands to make the terminal save the current cursor
  401.      position.  Only the last saved position can be used.  If this
  402.      capability is present, `rc' should be provided also.  Most
  403.      terminals have neither.
  404.      String of commands to make the terminal restore the last saved
  405.      cursor position.  If this capability is present, `sc' should be
  406.      provided also.  Most terminals have neither.
  407.      String of commands to advance to the next page, for a hardcopy
  408.      terminal.
  409.      String of commands to move the cursor right to the next hardware
  410.      tab stop column.  Missing if the terminal does not have any kind
  411.      of hardware tabs.  Do not send this command if the kernel's
  412.      terminal modes say that the kernel is expanding tabs into spaces.
  413.      String of commands to move the cursor left to the previous
  414.      hardware tab stop column.  Missing if the terminal has no such
  415.      ability; many terminals do not.  Do not send this command if the
  416.      kernel's terminal modes say that the kernel is expanding tabs
  417.      into spaces.
  418.    The following obsolete capabilities should be included in terminal
  419. descriptions when appropriate, but should not be looked at by new
  420. programs.
  421.      Flag whose presence means the terminal does not support the ASCII
  422.      carriage return character as `cr'.  This flag is needed because
  423.      old programs assume, when the `cr' capability is missing, that
  424.      ASCII carriage return can be used for the purpose.  We use `nc'
  425.      to tell the old programs that carriage return may not be used.
  426.      New programs should not assume any default for `cr', so they need
  427.      not look at `nc'.  However, descriptions should contain `nc'
  428.      whenever they do not contain `cr'.
  429.      Flag whose presence means that the ASCII tab character may not be
  430.      used for cursor motion.  This flag exists because old programs
  431.      assume, when the `ta' capability is missing, that ASCII tab can
  432.      be used for the purpose.  We use `xt' to tell the old programs
  433.      not to use tab.
  434.      New programs should not assume any default for `ta', so they need
  435.      not look at `xt' in connection with cursor motion.  Note that
  436.      `xt' also has implications for standout mode (*note Standout::.). 
  437.      It is obsolete in regard to cursor motion but not in regard to
  438.      standout.
  439.      In fact, `xt' means that the terminal is a Teleray 1061.
  440.      Very obsolete alternative name for the `le' capability.
  441.      Flag whose presence means that the ASCII character backspace may
  442.      be used to move the cursor left.  Obsolete; look at `le' instead.
  443.      Obsolete capability which is a string that can either be used to
  444.      move the cursor down or to scroll.  The same string must scroll
  445.      when used on the bottom line and move the cursor when used on any
  446.      other line.  New programs should use `do' or `sf', and ignore
  447.      `nl'.
  448.      If there is no `nl' capability, some old programs assume they can
  449.      use the newline character for this purpose.  These programs
  450.      follow a bad practice, but because they exist, it is still
  451.      desirable to define the `nl' capability in a terminal description
  452.      if the best way to move down is *not* a newline.
  453. File: termcap.info,  Node: Wrapping,  Next: Scrolling,  Prev: Cursor Motion,  Up: Capabilities
  454. Wrapping
  455. ========
  456.    "Wrapping" means moving the cursor from the right margin to the left
  457. margin of the following line.  Some terminals wrap automatically when a
  458. graphic character is output in the last column, while others do not. 
  459. Most application programs that use termcap need to know whether the
  460. terminal wraps.  There are two special flag capabilities to describe
  461. what the terminal does when a graphic character is output in the last
  462. column.
  463.      Flag whose presence means that writing a character in the last
  464.      column causes the cursor to wrap to the beginning of the next
  465.      line.
  466.      If `am' is not present, writing in the last column leaves the
  467.      cursor at the place where the character was written.
  468.      Writing in the last column of the last line should be avoided on
  469.      terminals with `am', as it may or may not cause scrolling to
  470.      occur (*note Scrolling::.).  Scrolling is surely not what you
  471.      would intend.
  472.      If your program needs to check the `am' flag, then it also needs
  473.      to check the `xn' flag which indicates that wrapping happens in a
  474.      strange way.  Many common terminals have the `xn' flag.
  475.      Flag whose presence means that the cursor wraps in a strange way.
  476.       At least two distinct kinds of strange behavior are known; the
  477.      termcap data base does not contain anything to distinguish the
  478.      two.
  479.      On Concept-100 terminals, output in the last column wraps the
  480.      cursor almost like an ordinary `am' terminal.  But if the next
  481.      thing output is a newline, it is ignored.
  482.      DEC VT-100 terminals (when the wrap switch is on) do a different
  483.      strange thing: the cursor wraps only if the next thing output is
  484.      another graphic character.  In fact, the wrap occurs when the
  485.      following graphic character is received by the terminal, before
  486.      the character is placed on the screen.
  487.      On both of these terminals, after writing in the last column a
  488.      following graphic character will be displayed in the first column
  489.      of the following line.  But the effect of relative cursor motion
  490.      characters such as newline or backspace at such a time depends on
  491.      the terminal.  The effect of erase or scrolling commands also
  492.      depends on the terminal.  You can't assume anything about what
  493.      they will do on a terminal that has `xn'.  So, to be safe, you
  494.      should never do these things at such a time on such a terminal.
  495.      To be sure of reliable results on a terminal which has the `xn'
  496.      flag, output a `cm' absolute positioning command after writing in
  497.      the last column.  Another safe thing to do is to output
  498.      carriage-return newline, which will leave the cursor at the
  499.      beginning of the following line.
  500. File: termcap.info,  Node: Scrolling,  Next: Windows,  Prev: Wrapping,  Up: Capabilities
  501. Scrolling
  502. =========
  503.    "Scrolling" means moving the contents of the screen up or down one
  504. or more lines.  Moving the contents up is "forward scrolling"; moving
  505. them down is "reverse scrolling".
  506.    Scrolling happens after each line of output during ordinary output
  507. on most display terminals.  But in an application program that uses
  508. termcap for random-access output, scrolling happens only when
  509. explicitly requested with the commands in this section.
  510.    Some terminals have a "scroll region" feature.  This lets you limit
  511. the effect of scrolling to a specified range of lines.  Lines outside
  512. the range are unaffected when scrolling happens.  The scroll region
  513. feature is available if either `cs' or `cS' is present.
  514.      String of commands to scroll the screen one line up, assuming it
  515.      is output with the cursor at the beginning of the bottom line.
  516.      String of commands to scroll the screen one line down, assuming
  517.      it is output with the cursor at the beginning of the top line.
  518.      A few programs will try to use `do' to do the work of `sf'.  This
  519.      is not really correct--it is an attempt to compensate for the
  520.      absence of a `sf' command in some old terminal descriptions.
  521.      Since these terminal descriptions do define `sr', perhaps at one
  522.      time the definition of `do' was different and it could be used
  523.      for scrolling as well.  But it isn't desirable to combine these
  524.      two functions in one capability, since scrolling often requires
  525.      more padding than simply moving the cursor down.  Defining `sf'
  526.      and `do' separately allows you to specify the padding properly. 
  527.      Also, all sources agree that `do' should not be relied on to do
  528.      scrolling.
  529.      So the best approach is to add `sf' capabilities to the
  530.      descriptions of these terminals, copying the definition of `do'
  531.      if that does scroll.
  532.      String of commands to scroll the screen N lines up, assuming it
  533.      is output with the cursor at the beginning of the bottom line.
  534.      String of commands to scroll the screen N lines down, assuming it
  535.      is output with the cursor at the beginning of the top line.
  536.      String of commands to set the scroll region.  This command takes
  537.      two parameters, START and END, which are the line numbers
  538.      (origin-zero) of the first line to include in the scroll region
  539.      and of the last line to include in it.  When a scroll region is
  540.      set, scrolling is limited to the specified range of lines; lines
  541.      outside the range are not affected by scroll commands.
  542.      Do not try to move the cursor outside the scroll region.  The
  543.      region remains set until explicitly removed.  To remove the
  544.      scroll region, use another `cs' command specifying the full
  545.      height of the screen.
  546.      The cursor position is undefined after the `cs' command is set,
  547.      so position the cursor with `cm' immediately afterward.
  548.      String of commands to set the scroll region using parameters in
  549.      different form.  The effect is the same as if `cs' were used. 
  550.      Four parameters are required:
  551.        1. Total number of lines on the screen.
  552.        2. Number of lines above desired scroll region.
  553.        3. Number of lines below (outside of) desired scroll region.
  554.        4. Total number of lines on the screen, the same as the first
  555.           parameter.
  556.      This capability is a GNU extension that was invented to allow the
  557.      Ann Arbor Ambassador's scroll-region command to be described; it
  558.      could also be done by putting non-Unix `%'-sequences into a `cs'
  559.      string, but that would have confused Unix programs that used the
  560.      `cs' capability with the Unix termcap.  Currently only GNU Emacs
  561.      uses the `cS' capability.
  562.      Flag which means that the terminal does not normally scroll for
  563.      ordinary sequential output.  For modern terminals, this means that
  564.      outputting a newline in ordinary sequential output with the
  565.      cursor on the bottom line wraps to the top line.  For some
  566.      obsolete terminals, other things may happen.
  567.      The terminal may be able to scroll even if it does not normally
  568.      do so.  If the `sf' capability is provided, it can be used for
  569.      scrolling regardless of `ns'.
  570.      Flag whose presence means that lines scrolled up off the top of
  571.      the screen may come back if scrolling down is done subsequently.
  572.      The `da' and `db' flags do not, strictly speaking, affect how to
  573.      scroll.  But programs that scroll usually need to clear the lines
  574.      scrolled onto the screen, if these flags are present.
  575.      Flag whose presence means that lines scrolled down off the bottom
  576.      of the screen may come back if scrolling up is done subsequently.
  577.      Numeric value, the number of lines of display memory that the
  578.      terminal has.  A value of zero means that the terminal has more
  579.      display memory than can fit on the screen, but no fixed number of
  580.      lines.  (The number of lines may depend on the amount of text in
  581.      each line.)
  582.    Any terminal description that defines `SF' should also define `sf';
  583. likewise for `SR' and `sr'.  However, many terminals can only scroll
  584. by one line at a time, so it is common to find `sf' and not `SF', or
  585. `sr' without `SR'.
  586.    Therefore, all programs that use the scrolling facilities should be
  587. prepared to work with `sf' in the case that `SF' is absent, and
  588. likewise with `sr'.  On the other hand, an application program that
  589. uses only `sf' and not `SF' is acceptable, though slow on some
  590. terminals.
  591.    When outputting a scroll command with `tputs', the NLINES argument
  592. should be the total number of lines in the portion of the screen being
  593. scrolled.  Very often these commands require padding proportional to
  594. this number of lines.  *Note Padding::.
  595. File: termcap.info,  Node: Windows,  Next: Clearing,  Prev: Scrolling,  Up: Capabilities
  596. Windows
  597. =======
  598.    A "window", in termcap, is a rectangular portion of the screen to
  599. which all display operations are restricted.  Wrapping, clearing,
  600. scrolling, insertion and deletion all operate as if the specified
  601. window were all the screen there was.
  602.      String of commands to set the terminal output screen window. 
  603.      This string requires four parameters, all origin-zero:
  604.        1. The first line to include in the window.
  605.        2. The last line to include in the window.
  606.        3. The first column to include in the window.
  607.        4. The last column to include in the window.
  608.    Most terminals do not support windows.
  609. File: termcap.info,  Node: Clearing,  Next: Insdel Line,  Prev: Windows,  Up: Capabilities
  610. Clearing Parts of the Screen
  611. ============================
  612.    There are several terminal capabilities for clearing parts of the
  613. screen to blank.  All display terminals support the `cl' string, and
  614. most display terminals support all of these capabilities.
  615.      String of commands to clear the entire screen and position the
  616.      cursor at the upper left corner.
  617.      String of commands to clear the line the cursor is on, and all the
  618.      lines below it, down to the bottom of the screen.  This command
  619.      string should be used only with the cursor in column zero; their
  620.      effect is undefined if the cursor is elsewhere.
  621.      String of commands to clear from the cursor to the end of the
  622.      current line.
  623.      String of commands to clear N characters, starting with the
  624.      character that the cursor is on.  This command string is expected
  625.      to leave the cursor position unchanged.  The parameter N should
  626.      never be large enough to reach past the right margin; the effect
  627.      of such a large parameter would be undefined.
  628.    Clear to end of line (`ce') is extremely important in programs that
  629. maintain an updating display.  Nearly all display terminals support
  630. this operation, so it is acceptable for a an application program to
  631. refuse to work if `ce' is not present.  However, if you do not want
  632. this limitation, you can accomplish clearing to end of line by
  633. outputting spaces until you reach the right margin.  In order to do
  634. this, you must know the current horizontal position.  Also, this
  635. technique assumes that writing a space will erase.  But this happens
  636. to be true on all the display terminals that fail to support `ce'.
  637. File: termcap.info,  Node: Insdel Line,  Next: Insdel Char,  Prev: Clearing,  Up: Capabilities
  638. Insert/Delete Line
  639. ==================
  640.    "Inserting a line" means creating a blank line in the middle of the
  641. screen, and pushing the existing lines of text apart.  In fact, the
  642. lines above the insertion point do not change, while the lines below
  643. move down, and one is normally lost at the bottom of the screen.
  644.    "Deleting a line" means causing the line to disappear from the
  645. screen, closing up the gap by moving the lines below it upward.  A new
  646. line appears at the bottom of the screen.  Usually this line is blank,
  647. but on terminals with the `db' flag it may be a line previously moved
  648. off the screen bottom by scrolling or line insertion.
  649.    Insertion and deletion of lines is useful in programs that maintain
  650. an updating display some parts of which may get longer or shorter. 
  651. They are also useful in editors for scrolling parts of the screen, and
  652. for redisplaying after lines of text are killed or inserted.
  653.    Many terminals provide commands to insert or delete a single line
  654. at the cursor position.  Some provide the ability to insert or delete
  655. several lines with one command, using the number of lines to insert or
  656. delete as a parameter.  Always move the cursor to column zero before
  657. using any of these commands.
  658.      String of commands to insert a blank line before the line the
  659.      cursor is on.  The existing line, and all lines below it, are
  660.      moved down.  The last line in the screen (or in the scroll
  661.      region, if one is set) disappears and in most circumstances is
  662.      discarded.  It may not be discarded if the `db' is present (*note
  663.      Scrolling::.).
  664.      The cursor must be at the left margin before this command is used. 
  665.      This command does not move the cursor.
  666.      String of commands to delete the line the cursor is on.  The
  667.      following lines move up, and a blank line appears at the bottom
  668.      of the screen (or bottom of the scroll region).  If the terminal
  669.      has the `db' flag, a nonblank line previously pushed off the
  670.      screen bottom may reappear at the bottom.
  671.      The cursor must be at the left margin before this command is used. 
  672.      This command does not move the cursor.
  673.      String of commands to insert N blank lines before the line that
  674.      the cursor is on.  It is like `al' repeated N times, except that
  675.      it is as fast as one `al'.
  676.      String of commands to delete N lines starting with the line that
  677.      the cursor is on.  It is like `dl' repeated N times, except that
  678.      it is as fast as one `dl'.
  679.    Any terminal description that defines `AL' should also define `al';
  680. likewise for `DL' and `dl'.  However, many terminals can only insert
  681. or delete one line at a time, so it is common to find `al' and not
  682. `AL', or `dl' without `DL'.
  683.    Therefore, all programs that use the insert and delete facilities
  684. should be prepared to work with `al' in the case that `AL' is absent,
  685. and likewise with `dl'.  On the other hand, it is acceptable to write
  686. an application that uses only `al' and `dl' and does not look for `AL'
  687. or `DL' at all.
  688.    If a terminal does not support line insertion and deletion directly,
  689. but does support a scroll region, the effect of insertion and deletion
  690. can be obtained with scrolling.  However, it is up to the individual
  691. user program to check for this possibility and use the scrolling
  692. commands to get the desired result.  It is fairly important to
  693. implement this alternate strategy, since it is the only way to get the
  694. effect of line insertion and deletion on the popular VT100 terminal.
  695.    Insertion and deletion of lines is affected by the scroll region on
  696. terminals that have a settable scroll region.  This is useful when it
  697. is desirable to move any few consecutive lines up or down by a few
  698. lines.  *Note Scrolling::.
  699.    The line pushed off the bottom of the screen is not lost if the
  700. terminal has the `db' flag capability; instead, it is pushed into
  701. display memory that does not appear on the screen.  This is the same
  702. thing that happens when scrolling pushes a line off the bottom of the
  703. screen.  Either reverse scrolling or deletion of a line can bring the
  704. apparently lost line back onto the bottom of the screen.  If the
  705. terminal has the scroll region feature as well as `db', the pushed-out
  706. line really is lost if a scroll region is in effect.
  707.    When outputting an insert or delete command with `tputs', the
  708. NLINES argument should be the total number of lines from the cursor to
  709. the bottom of the screen (or scroll region).  Very often these commands
  710. require padding proportional to this number of lines.  *Note Padding::.
  711.    For `AL' and `DL' the NLINES argument should *not* depend on the
  712. number of lines inserted or deleted; only the total number of lines
  713. affected.  This is because it is just as fast to insert two or N lines
  714. with `AL' as to insert one line with `al'.
  715.